Skip to content

feat: polyglot script engine for code-based load testing#36

Merged
rlaope merged 11 commits intomasterfrom
feat/script-engine
Apr 5, 2026
Merged

feat: polyglot script engine for code-based load testing#36
rlaope merged 11 commits intomasterfrom
feat/script-engine

Conversation

@rlaope
Copy link
Copy Markdown
Owner

@rlaope rlaope commented Apr 5, 2026

Summary

  • Add kar script command for code-based load testing with kar98k's chaos patterns
  • Polyglot support: Starlark (.star), JavaScript (.js), and external process protocol (.py, .rb, .lua)
  • chaos() as first-class API primitive — unique differentiator vs k6/Locust/Gatling
  • VU scheduling with ramp stages, checks, thresholds, setup/teardown lifecycle

How it works

# Starlark (Python-like)
kar script test.star --vus 10 --duration 2m

# JavaScript
kar script test.js --preset aggressive

# Any language via JSON-line protocol
kar script test.py

Example (.star)

scenario(
    name = "checkout-flow",
    pattern = chaos(preset = "aggressive", spike_factor = 3.0),
    vus = ramp([stage("30s", 20), stage("1m", 50), stage("10s", 0)]),
    thresholds = {"http_req_duration{p95}": "< 500ms"},
)

def default(data):
    resp = http.get("http://localhost:8080/health")
    check(resp, {"status 200": lambda r: r.status == 200})
    sleep(think_time("1s", "3s"))

Verified

Language Requests RPS Errors Checks
Starlark 9,276 1,153 0 100%
JavaScript 2,967 368 0 100%
Starlark (multi-step) 781 15.6 0 100%

Test plan

  • Starlark basic test (single endpoint, 3 VUs, 8s)
  • JavaScript basic test (single endpoint, 3 VUs, 8s)
  • Multi-step scenario with VU ramping (setup/teardown, think_time, stages)
  • Check/threshold evaluation and reporting
  • External process protocol (.py) integration test

rlaope added 2 commits April 5, 2026 15:05
@rlaope
feat: add polyglot script engine for code-based load testing
6421237 
Add `kar script` command supporting multiple languages:
- Starlark (.star) - Python-like, built-in, goroutine-safe
- JavaScript (.js) - ES5+ via goja, built-in
- External process protocol (.py, .rb, .lua) - JSON-line IPC

Key features:
- chaos() primitive as first-class API (unique to kar98k)
- VU scheduling with ramp stages
- Checks and thresholds with pass/fail reporting
- think_time() for chaos-aware delays
- setup/teardown lifecycle hooks
- Detailed test report with latency percentiles

Architecture:
- Runner interface for polyglot backend support
- VUScheduler for virtual user lifecycle management
- Auto-detect language from file extension

Signed-off-by: rlaope <piyrw9754@gmail.com>
@rlaope
fix: resolve vet error in script vu.go
4353361 
Replace fmt.Println with fmt.Print for strings containing newlines.

Signed-off-by: rlaope <piyrw9754@gmail.com>
@rlaope rlaope force-pushed the feat/script-engine branch from 6b85d71 to 4353361 Compare April 5, 2026 06:05
rlaope added 9 commits April 5, 2026 15:12
@rlaope
fix: external runner goroutine safety and Python example
bebeebf 
- Fix nil body reader crash in newHTTPRequest
- Add mutex for goroutine-safe external process communication
- Fix chaos config preset parsing for external runners
- Add Python example script using JSON-line protocol

Signed-off-by: rlaope <piyrw9754@gmail.com>
@rlaope
feat: add Python SDK for native code-based load testing
1d82f80 
- Python SDK (sdk/python/kar98k.py) wraps JSON-line protocol
- Users write natural Python: http.get(), check(), sleep()
- SDK auto-starts protocol loop via atexit
- External runner now sends HTTP responses back to scripts
- Example: examples/basic_test.py using SDK

Signed-off-by: rlaope <piyrw9754@gmail.com>
@rlaope
feat: add Python and Ruby SDKs for native load testing
ee77ecd 
- Python SDK (sdk/python/kar98k.py): from kar98k import http, check
- Ruby SDK (sdk/ruby/kar98k.rb): require 'kar98k'
- External runner sends HTTP responses back to scripts
- Both SDKs auto-start protocol loop via atexit/at_exit
- Verified: Python 3.x and Ruby 2.6+ compatible

Signed-off-by: rlaope <piyrw9754@gmail.com>
@rlaope
feat: add real-time web dashboard for script execution
708e021 
- Web dashboard at localhost:8888 with --dashboard flag
- SSE-based real-time stats streaming (1s interval)
- Sky blue + black theme matching CLI aesthetic
- Live RPS and latency charts (Canvas-based, no dependencies)
- Real-time checks, status codes, error rate display
- Single HTML file embedded in Go binary

Signed-off-by: rlaope <piyrw9754@gmail.com>
@rlaope
feat: redesign dashboard UI and update README
f6b9af5 
- Clean Locust-style dashboard: data-focused, no visual clutter
- Top stat bar, dual charts, side panels for checks/status codes
- Add Script Engine section to README with polyglot examples

Signed-off-by: rlaope <piyrw9754@gmail.com>
@rlaope
feat: dashboard trigger mode and enhanced metrics
042a3cc 
- Add --wait flag: dashboard shows Start button, test waits for trigger
- Add Start/Stop buttons to dashboard UI
- Add /api/start, /api/stop, /api/state endpoints
- Add peak tracking for RPS, latency, P95, VUs
- Add RPS history panel with spike detection (>1.5x avg)
- Add descriptions to each chart and panel explaining what metrics mean
- Two modes: kar script test.star --dashboard (auto-run)
             kar script test.star --dashboard --wait (trigger from UI)

Signed-off-by: rlaope <piyrw9754@gmail.com>
@rlaope
fix: dashboard Start/Stop/Restart cycle
d7da774 
- Stop after test shows Start button again for re-run
- --wait mode loops: Start → Run → Stop → Start → ...
- Process stays alive between runs in --wait mode
- Non-wait mode unchanged (runs once)

Signed-off-by: rlaope <piyrw9754@gmail.com>
@rlaope
feat: add simulated failures to echo server
fce06e5 
- 10% chance: 500 error + 1~3s delay
- 5% chance: 400 bad request
- 3% chance: slow response (200~700ms, no error)
- Applied to /health, /api/users list, /api/echo

Signed-off-by: rlaope <piyrw9754@gmail.com>
@rlaope
docs: add dashboard screenshot to README
63821c6 
Signed-off-by: rlaope <piyrw9754@gmail.com>
@rlaope rlaope merged commit 59aafb9 into master Apr 5, 2026
4 checks passed
rlaope added a commit that referenced this pull request Apr 5, 2026
@rlaope
Merge pull request #36 from rlaope/feat/script-engine
d158354 
feat: polyglot script engine for code-based load testing
rlaope added a commit that referenced this pull request Apr 5, 2026
@rlaope
Merge pull request #36 from rlaope/feat/script-engine
58c9016 
feat: polyglot script engine for code-based load testing
rlaope added a commit that referenced this pull request Apr 5, 2026
@rlaope
Merge pull request #36 from rlaope/feat/script-engine
f9787ed 
feat: polyglot script engine for code-based load testing
rlaope pushed a commit that referenced this pull request Apr 5, 2026
@rlaope-ai
Merge pull request #36 from rlaope/feat/script-engine
9b431a8 
feat: polyglot script engine for code-based load testing
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@rlaope